home *** CD-ROM | disk | FTP | other *** search
/ User's Choice Windows CD / User's Choice Windows CD (CMS Software)(1993).iso / utility3 / pbcwin.zip / PBCWIN.DOC < prev    next >
Text File  |  1993-01-22  |  34KB  |  1,130 lines

  1.                  The PBClone Windows Library
  2.                =-----------------------------=
  3.                          Version 1.0
  4.  
  5.        PBCwin  Copyright (c) 1993  Thomas G. Hanlin III
  6.  
  7.  
  8.  
  9. This is PBCwin, a general-purpose library of 79 routines for
  10. use with Visual Basic for Windows.  The PBCwin collection is
  11. copyrighted and may be distributed only under the following
  12. conditions:
  13.  
  14.    All PBCwin files must be distributed together as a unit.
  15.    No files may be altered, added, or deleted from this unit.
  16.  
  17. You use this library at your own risk.  It has been tested by
  18. me on my own computer, but I will not assume any responsibility
  19. for any problems which PBCwin may cause you.  If you do run
  20. into a problem, please let me know about it, and I will do my
  21. best to verify and repair it.
  22.  
  23. It is expected that if you find PBCwin useful, you will
  24. register your copy.  You may not use PBCwin routines in
  25. programs intended for sale unless you have registered.
  26.  
  27. Registration gives you the right to distribute the PBCWIN.DLL
  28. library with your programs.  It also gets you the latest
  29. version of PBCwin, complete with full source code (written in
  30. Microsoft C 7.0).
  31.  
  32. The PBCwin library can be used with any Windows language that
  33. can access DLLs.  It is currently documented only for VB/Win,
  34. however.  I expect to extend the documentation to cover other
  35. languages in future versions.  PBCwin will be expanding greatly
  36. over the course of the next year or so, as I get a better grip
  37. on the idiosyncracies of Windows programming.
  38.  
  39. If you're familiar with DOS libraries, you'll have no trouble
  40. at all with Windows libraries.  There's one important thing to
  41. keep in mind, however.  DOS libraries are almost always linked
  42. into your .EXE program and become an integral part of it.
  43. Windows libraries are separate from your program and must be
  44. available to Windows when your program is run.  This allows
  45. multiple programs to share the same library code for greater
  46. memory efficiency.  It also means you will need to distribute
  47. the PBCWIN.DLL file with your programs that use it (legal only
  48. for registered PBCwin owners), or simply tell people where they
  49. can get a copy of PBCwin to use with your program.
  50.  
  51. In order to use any of the PBCwin routines in a VB/Win program,
  52. you must place the appropriate declarations in the globals
  53. section of the program.  These declarations can be taken
  54. individually or en masse from the PBCWIN.BI text file.
  55.  
  56. The PBCwinVer function will let you make sure that the version
  57. of PBCWIN.DLL that is being used is, in fact, sufficiently
  58. current as to support the routines your program requires.
  59.  
  60. Name  : BinI                 (Binary Integer)
  61.  
  62. This function converts a binary value, passed to it as a
  63. string, to an integer.  It stops the conversion on reaching the
  64. end of the string or at the first character that is not a valid
  65. binary digit ("0" or "1").
  66.  
  67. See also BinL, which returns a long integer value.
  68.  
  69.    Result% = BinI(St$)
  70.  
  71. St$       binary number, in string form
  72. -------
  73. Result%   integer equivalent of binary number
  74.  
  75. Name  : BinL                 (Binary Long)
  76.  
  77. This function converts a binary value, passed to it as a
  78. string, to a long integer.  It stops the conversion on reaching
  79. the end of the string or at the first character that is not a
  80. valid binary digit ("0" or "1").
  81.  
  82. See also BinI, which returns an integer value.
  83.  
  84.    Result& = BinL(St$)
  85.  
  86. St$       binary number, in string form
  87. -------
  88. Result&   long integer equivalent of binary number
  89.  
  90. Name  : Bytes2Int            (Bytes to Integer)
  91.  
  92. This function combines two bytes, contained in separate
  93. integers, into a single integer value.
  94.  
  95. See also HiByte and LoByte, which may be used to reverse the
  96. process, splitting an integer into two bytes.
  97.  
  98.    Result% = Bytes2Int(Lo%, Hi%)
  99.  
  100. Lo%       low, or least significant, byte
  101. Hi%       high, or most significant, byte
  102. -------
  103. Result%   result of combining bytes into an integer
  104.  
  105. Name  : Checksum             (Checksum)
  106.  
  107. This function calculates an 8-bit checksum for a string.  The
  108. result is compatible with Xmodem and Ymodem file transfer
  109. protocols, and can be used as a fast and simple check of data
  110. validity.  For more rigorous testing, see CRC16.
  111.  
  112.    Result% = Checksum(St$, Bytes%)
  113.  
  114. St$       string for which to calculate checksum
  115. Bytes%    number of characters for which to calculate checksum
  116. -------
  117. Result%   checksum of specified part of string
  118.  
  119. Name  : ComPorts             (Comm Ports)
  120.  
  121. This function returns the number of communications (serial)
  122. ports installed.
  123.  
  124.    Result% = ComPorts()
  125.  
  126. -------
  127. Result%   comm ports (0-3)
  128.  
  129. Name  : CRC16                (CRC, 16-bit)
  130.  
  131. This function calculates a 16-bit "cyclical redundancy check"
  132. checksum, or CRC, for a string.  The result is compatible with
  133. Xmodem and Ymodem file transfer protocols, and can be used as a
  134. check of data validity.
  135.  
  136. Note that the Xmodem and Ymodem file transfer protocols use a
  137. different byte ordering method than typical of Intel machines.
  138. If you intend to use this function in writing file transfer
  139. protocols, you will need to reverse the byte order to MSB
  140. first, LSB second.  This can be accomplished with either
  141. LRotateI or RRotateI with a shift count of 8 (eight), or by
  142. splitting the integer into bytes with LoByte and HiByte, and
  143. swapping the results.
  144.  
  145.    Result% = CRC16(St$, Bytes%)
  146.  
  147. St$       string for which to calculate CRC
  148. Bytes%    number of characters for which to calculate CRC
  149. -------
  150. Result%   CRC of specified part of string
  151.  
  152. Name  : DateSq               (Date Squeeze)
  153.  
  154. This function compresses a date into a single integer.  This
  155. provides a very efficient storage format for dates ranging from
  156. January 1, 1900 to December 31, 2028.
  157.  
  158. Uncompression is done with DayUnsq, MonthUnsq, and YearUnsq.
  159. See also TimeSq, which allows you to compress a time value
  160. similarly.
  161.  
  162. Note that compressed dates are not in a format that may be
  163. readily used for comparison or date math purposes.  If you need
  164. such capabilities, convert the date to a BASIC time/date serial
  165. number first-- see your BASIC manual for details.
  166.  
  167. If you pass a year of 0-99, it will be translated to 1900-1999
  168. before the compression is done.  Depending on your application,
  169. you may wish to assume 0-28 is the same as 2000-2028 instead.
  170. If so, make sure you do an explicit conversion before this
  171. function is called.
  172.  
  173.    Result% = DateSq(MonthNr%, DayNr%, YearNr%)
  174.  
  175. MonthNr%    month number (1-12)
  176. DayNr%      day number (1-31)
  177. YearNr%     year number (1900-2028)
  178. -------
  179. Result%     compressed date
  180.  
  181. Name  : DayUnsq              (Day Unsqueeze)
  182.  
  183. This function returns the day from a compressed date.  It works
  184. in conjunction with the DateSq date compression function.
  185.  
  186.    DayNr% = DayUnsq(Number%)
  187.  
  188. Number%     compressed date
  189. -------
  190. DayNr%      day number
  191.  
  192. Name  : Floppies             (Floppies)
  193.  
  194. This function returns the number of floppy disk drives
  195. installed, up to two.  Although it is possible to have up to
  196. four floppy drives, the PC was designed to expect a maximum of
  197. two, and this routine can't tell if there are more than that.
  198.  
  199.    Result% = Floppies()
  200.  
  201. -------
  202. Result%   floppy drives (0-2)
  203.  
  204. Name  : GetComAddr           (Get Comm Address)
  205.  
  206. This function returns the I/O base port address for a specified
  207. communications (serial) port.  If there is no such serial port,
  208. or if the port is in use, a zero will be returned.
  209.  
  210.    Address% = GetComAddr(PortNr%)
  211.  
  212. PortNr%     communications port number (0-3)
  213. -------
  214. Address%    I/O base port address for comm port
  215.  
  216. Name  : GetPrtAddr           (Get Prt Address)
  217.  
  218. This function returns the I/O base port address for a specified
  219. printer (parallel) port.  If there is no such parallel port, a
  220. zero will be returned.
  221.  
  222.    Address% = GetPrtAddr(PortNr%)
  223.  
  224. PortNr%     printer port number (0-3)
  225. -------
  226. Address%    I/O base port address for printer port
  227.  
  228. Name  : GetTick              (Get clock Tick)
  229.  
  230. This function returns the current system time count.  The count
  231. is the amount of time after midnight, in (approximately) 1/18th
  232. seconds.  This can be used as a fairly high-resolution timer.
  233.  
  234. DO NOT use this function to write a delay routine!  That would
  235. eat precious system time that could be more profitably used by
  236. other programs while your program is idle-- remember, Windows
  237. is a multitasking environment.  If you need a delay, use the
  238. SLEEP statement provided by BASIC.
  239.  
  240.    Result& = GetTick()
  241.  
  242. -------
  243. Result&   system timer tick
  244.  
  245. Name  : HiByte               (High Byte)
  246.  
  247. This function returns the high, or most significant, byte of an
  248. integer.
  249.  
  250. See also Bytes2Int, which can be used to reverse the process.
  251.  
  252.    Byte% = HiByte(Number%)
  253.  
  254. Number%     number from which to pick high byte
  255. -------
  256. Byte%       high byte of number
  257.  
  258. Name  : HiNybble             (High Nybble)
  259.  
  260. This function returns the high, or most significant, nybble of
  261. a byte.
  262.  
  263. See also Nybs2Byte, which can be used to reverse the process.
  264.  
  265.    Nybble% = HiNybble(Number%)
  266.  
  267. Number%     byte from which to pick high nybble
  268. -------
  269. Nybble%     high nybble of byte
  270.  
  271. Name  : HiWord               (High Word)
  272.  
  273. This function returns the high, or most significant, word of a
  274. long integer.
  275.  
  276. See also Ints2Long, which can be used to reverse the process.
  277.  
  278.    Word% = HiWord(Number&)
  279.  
  280. Number&     long integer from which to pick high word
  281. -------
  282. Word%       high word of long integer
  283.  
  284. Name  : HourUnsq             (Hour Unsqueeze)
  285.  
  286. This function returns the hour from a compressed time.  It
  287. works in conjunction with the TimeSq time compression function.
  288.  
  289.    HourNr% = HourUnsq(Number%)
  290.  
  291. Number%     compressed time
  292. -------
  293. HourNr%     hour number
  294.  
  295. Name  : Ints2Long            (Integers to Long)
  296.  
  297. This function combines two integers into a single long integer
  298. value.
  299.  
  300. See also HiWord and LoWord, which may be used to reverse the
  301. process, splitting a long integer into two integers.
  302.  
  303.    Result& = Ints2Long(Lo%, Hi%)
  304.  
  305. Lo%       low, or least significant, word
  306. Hi%       high, or most significant, word
  307. -------
  308. Result&   result of combining integers into a long
  309.  
  310. Name  : IsAlNum              (Is AlphaNumeric)
  311.  
  312. This function tells you whether a character is alphanumeric,
  313. that is, either a letter of the alphabet or a digit.  It
  314. operates on the first character of a string you pass it.
  315.  
  316.    Result% = IsAlNum(St$)
  317.  
  318. St$        character to test
  319. -------
  320. Result%    whether char is alphanumeric (-1 yes, 0 no)
  321.  
  322. Name  : IsAlpha              (Is Alphabetic)
  323.  
  324. This function tells you whether a character is alphabetic.  It
  325. operates on the first character of a string you pass it.
  326.  
  327.    Result% = IsAlpha(St$)
  328.  
  329. St$        character to test
  330. -------
  331. Result%    whether char is alphabetic (-1 yes, 0 no)
  332.  
  333. Name  : IsASCII              (Is ASCII)
  334.  
  335. This function tells you whether a character is a member of the
  336. ASCII character set.  It operates on the first character of a
  337. string you pass it.
  338.  
  339.    Result% = IsASCII(St$)
  340.  
  341. St$        character to test
  342. -------
  343. Result%    whether char is ASCII (-1 yes, 0 no)
  344.  
  345. Name  : IsControl            (Is Control)
  346.  
  347. This function tells you whether a character is a control code.
  348. Control codes are considered to be ASCII 0-31 and 127.  This
  349. function operates on the first character of a string you pass
  350. it.
  351.  
  352.    Result% = IsControl(St$)
  353.  
  354. St$        character to test
  355. -------
  356. Result%    whether char is a control code (-1 yes, 0 no)
  357.  
  358. Name  : IsDigit              (Is Digit)
  359.  
  360. This function tells you whether a character is a digit. It
  361. operates on the first character of a string you pass it.
  362.  
  363.    Result% = IsDigit(St$)
  364.  
  365. St$        character to test
  366. -------
  367. Result%    whether char is a digit (-1 yes, 0 no)
  368.  
  369. Name  : IsLower              (Is Lowercase)
  370.  
  371. This function tells you whether a character is a lowercase
  372. letter ("a" through "z").  It operates on the first character
  373. of a string you pass it.
  374.  
  375.    Result% = IsLower(St$)
  376.  
  377. St$        character to test
  378. -------
  379. Result%    whether char is lowercase (-1 yes, 0 no)
  380.  
  381. Name  : IsPunct              (Is Punctuation)
  382.  
  383. This function tells you whether a character may be construed as
  384. punctuation.  This includes the space and most symbols. This
  385. function operates on the first character of a string you pass
  386. it.
  387.  
  388.    Result% = IsPunct(St$)
  389.  
  390. St$        character to test
  391. -------
  392. Result%    whether char is punctuation (-1 yes, 0 no)
  393.  
  394. Name  : IsSpace              (Is Space)
  395.  
  396. This function tells you whether a character is "white space"
  397. (ASCII 9-13 and 32, including tab, linefeed, formfeed, carriage
  398. return, and space).  It operates on the first character of a
  399. string you pass it.
  400.  
  401.    Result% = IsSpace(St$)
  402.  
  403. St$        character to test
  404. -------
  405. Result%    whether char is white space (-1 yes, 0 no)
  406.  
  407. Name  : IsUpper              (Is Uppercase)
  408.  
  409. This function tells you whether a character is an uppercase
  410. letter ("A" through "Z").  It operates on the first character
  411. of a string you pass it.
  412.  
  413.    Result% = IsUpper(St$)
  414.  
  415. St$        character to test
  416. -------
  417. Result%    whether char is uppercase (-1 yes, 0 no)
  418.  
  419. Name  : IsXDigit             (Is heX Digit)
  420.  
  421. This function tells you whether a character is a hexadecimal
  422. digit.  This includes 0-9, a-z, and A-Z.  This function
  423. operates on the first character of a string you pass it.
  424.  
  425.    Result% = IsXDigit(St$)
  426.  
  427. St$        character to test
  428. -------
  429. Result%    whether char is a hex digit (-1 yes, 0 no)
  430.  
  431. Name  : LoByte               (Low Byte)
  432.  
  433. This function returns the low, or least significant, byte of an
  434. integer.
  435.  
  436. See also Bytes2Int, which can be used to reverse the process.
  437.  
  438.    Byte% = LoByte(Number%)
  439.  
  440. Number%     number from which to pick low byte
  441. -------
  442. Byte%       low byte of number
  443.  
  444. Name  : LoNybble             (Low Nybble)
  445.  
  446. This function returns the low, or least significant, nybble of
  447. a byte.
  448.  
  449. See also Nybs2Byte, which can be used to reverse the process.
  450.  
  451.    Nybble% = LoNybble(Number%)
  452.  
  453. Number%     byte from which to pick low nybble
  454. -------
  455. Nybble%     low nybble of byte
  456.  
  457. Name  : LoWord               (Low Word)
  458.  
  459. This function returns the low, or least significant, word of a
  460. long integer.
  461.  
  462. See also Ints2Long, which can be used to reverse the process.
  463.  
  464.    Word% = LoWord(Number&)
  465.  
  466. Number&     long integer from which to pick low word
  467. -------
  468. Word%       low word of long integer
  469.  
  470. Name  : LRotateI             (Left Rotate Integer)
  471.  
  472. This function returns the result of rotating an integer left by
  473. a specified number of bits.
  474.  
  475.    Result% = LRotateI(Number%, Count%)
  476.  
  477. Number%     number to rotate
  478. Count%      number of bits by which to rotate
  479. -------
  480. Result%     rotated number
  481.  
  482. Name  : LRotateL             (Left Rotate Long)
  483.  
  484. This function returns the result of rotating a long integer
  485. left by a specified number of bits.
  486.  
  487.    Result& = LRotateL(Number&, Count%)
  488.  
  489. Number&     number to rotate
  490. Count%      number of bits by which to rotate
  491. -------
  492. Result&     rotated number
  493.  
  494. Name  : LShiftI             (Left Shift Integer)
  495.  
  496. This function returns the result of shifting an integer left by
  497. a specified number of bits.
  498.  
  499.    Result% = LShiftI(Number%, Count%)
  500.  
  501. Number%     number to shift
  502. Count%      number of bits by which to shift
  503. -------
  504. Result%     shifted number
  505.  
  506. Name  : LShiftL             (Left Shift Long)
  507.  
  508. This function returns the result of shifting a long integer
  509. left by a specified number of bits.
  510.  
  511.    Result& = LShiftL(Number&, Count%)
  512.  
  513. Number&     number to shift
  514. Count%      number of bits by which to shift
  515. -------
  516. Result&     shifted number
  517.  
  518. Name  : MaxD                 (Maximum Double-precision)
  519.  
  520. This function returns the larger of two double-precision
  521. numbers.
  522.  
  523.    Result# = MaxD(Nr1#, Nr2#)
  524.  
  525. Nr1#      first number
  526. Nr2#      second number
  527. -------
  528. Result#   larger of the two numbers
  529.  
  530. Name  : MaxI                 (Maximum Integer)
  531.  
  532. This function returns the larger of two integers.
  533.  
  534.    Result% = MaxI(Nr1%, Nr2%)
  535.  
  536. Nr1%      first number
  537. Nr2%      second number
  538. -------
  539. Result%   larger of the two numbers
  540.  
  541. Name  : MaxL                 (Maximum Long)
  542.  
  543. This function returns the larger of two long integers.
  544.  
  545.    Result& = MaxL(Nr1&, Nr2&)
  546.  
  547. Nr1&      first number
  548. Nr2&      second number
  549. -------
  550. Result&   larger of the two numbers
  551.  
  552. Name  : MaxS                 (Maximum Single-precision)
  553.  
  554. This function returns the larger of two single-precision
  555. numbers.
  556.  
  557.    Result! = MaxS(Nr1!, Nr2!)
  558.  
  559. Nr1!      first number
  560. Nr2!      second number
  561. -------
  562. Result!   larger of the two numbers
  563.  
  564. Name  : MinD                 (Minimum Double-precision)
  565.  
  566. This function returns the smaller of two double-precision
  567. numbers.
  568.  
  569.    Result# = MinD(Nr1#, Nr2#)
  570.  
  571. Nr1#      first number
  572. Nr2#      second number
  573. -------
  574. Result#   smaller of the two numbers
  575.  
  576. Name  : MinI                 (Minimum Integer)
  577.  
  578. This function returns the smaller of two integers.
  579.  
  580.    Result% = MinI(Nr1%, Nr2%)
  581.  
  582. Nr1%      first number
  583. Nr2%      second number
  584. -------
  585. Result%   smaller of the two numbers
  586.  
  587. Name  : MinL                 (Minimum Long)
  588.  
  589. This function returns the smaller of two long integers.
  590.  
  591.    Result& = MinL(Nr1&, Nr2&)
  592.  
  593. Nr1&      first number
  594. Nr2&      second number
  595. -------
  596. Result&   smaller of the two numbers
  597.  
  598. Name  : MinS                 (Minimum Single-precision)
  599.  
  600. This function returns the smaller of two single-precision
  601. numbers.
  602.  
  603.    Result! = MinS(Nr1!, Nr2!)
  604.  
  605. Nr1!      first number
  606. Nr2!      second number
  607. -------
  608. Result!   smaller of the two numbers
  609.  
  610. Name  : MinuteUnsq           (Minute Unsqueeze)
  611.  
  612. This function returns the minute from a compressed time.  It
  613. works in conjunction with the TimeSq time compression function.
  614.  
  615.    MinuteNr% = MinuteUnsq(Number%)
  616.  
  617. Number%     compressed time
  618. -------
  619. MinuteNr%   minute number
  620.  
  621. Name  : MonthUnsq            (Month Unsqueeze)
  622.  
  623. This function returns the month from a compressed date.  It
  624. works in conjunction with the DateSq date compression function.
  625.  
  626.    MonthNr% = MonthUnsq(Number%)
  627.  
  628. Number%     compressed date
  629. -------
  630. MonthNr%    month number
  631.  
  632. Name  : Nybs2Byte            (Nybbles to Byte)
  633.  
  634. This function combines two nybbles into a single byte value.
  635. Since BASIC supports neither byte nor nybble data types, the
  636. values are all kept in integers.
  637.  
  638. See also HiNybble and LoNybble, which may be used to reverse
  639. the process, splitting a byte into two nybbles.
  640.  
  641.    Result% = Nybs2Byte(Lo%, Hi%)
  642.  
  643. Lo%       low, or least significant, nybble
  644. Hi%       high, or most significant, nybble
  645. -------
  646. Result%   result of combining nybbles into a byte
  647.  
  648. Name  : Odd                  (Odd)
  649.  
  650. This function tells you whether an integer is an odd number.
  651.  
  652.    Result% = Odd(Number%)
  653.  
  654. Number%   number to test
  655. -------
  656. Result%   whether number is odd (-1 yes, 0 no)
  657.  
  658. Name  : OddL                 (Odd Long)
  659.  
  660. This function tells you whether a long integer is an odd number.
  661.  
  662.    Result% = OddL(Number&)
  663.  
  664. Number&   number to test
  665. -------
  666. Result%   whether number is odd (-1 yes, 0 no)
  667.  
  668. Name  : PBCwinVer            (PBCwin Version)
  669.  
  670. This function returns the version of PBCwin available.  You can
  671. use this to make sure the PBCWIN.DLL being used is sufficiently
  672. current to handle the routines you need.  Don't check the exact
  673. version number, since it should be ok for the user to have a
  674. newer version of PBCwin than your program expects.  Instead,
  675. make sure that the returned version number is greater than or
  676. equal to the version you expect.
  677.  
  678. The version number is multiplied by 100 so it can be returned
  679. as an integer.  For example, PBCwin v1.0 returns a result of
  680. 100 here.  PBCwin v1.1 will return 110, and so on.
  681.  
  682.    Version% = PBCwinVer()
  683.  
  684. -------
  685. Version%    PBCWIN.DLL version times 100
  686.  
  687. Name  : PeekB                (Peek Byte)
  688.  
  689. This routine gets a byte from a specified memory location. The
  690. memory location is specified as a pointer, which is a combined
  691. segment and offset value.  The VarPtr function can be used to
  692. get a pointer to a variable.  If you want to create a pointer
  693. to an address for which you know the segment and offset, you
  694. can use the Ints2Long function to do so, by loading the segment
  695. into the high word and offset into the low word.
  696.  
  697.    Nr% = PeekB(Ptr&)
  698.  
  699. Ptr&        far pointer
  700. -------
  701. Nr%         byte retrieved from memory
  702.  
  703. Name  : PeekI                (Peek Integer)
  704.  
  705. This routine gets an integer from a specified memory location.
  706. The memory location is specified as a pointer, which is a
  707. combined segment and offset value.  The VarPtr function can be
  708. used to get a pointer to a variable.  If you want to create a
  709. pointer to an address for which you know the segment and
  710. offset, you can use the Ints2Long function to do so, by loading
  711. the segment into the high word and offset into the low word.
  712.  
  713.    Nr% = PeekI(Ptr&)
  714.  
  715. Ptr&        far pointer
  716. -------
  717. Nr%         integer retrieved from memory
  718.  
  719. Name  : PeekL                (Peek Long)
  720.  
  721. This routine gets a long integer from a specified memory
  722. location. The memory location is specified as a pointer, which
  723. is a combined segment and offset value.  The VarPtr function
  724. can be used to get a pointer to a variable.  If you want to
  725. create a pointer to an address for which you know the segment
  726. and offset, you can use the Ints2Long function to do so, by
  727. loading the segment into the high word and offset into the low
  728. word.
  729.  
  730.    Nr& = PeekL(Ptr&)
  731.  
  732. Ptr&        far pointer
  733. -------
  734. Nr&         long integer retrieved from memory
  735.  
  736. Name  : PokeB                (Poke Byte)
  737.  
  738. This routine pokes a byte into a specified memory location. The
  739. memory location is specified as a pointer, which is a combined
  740. segment and offset value.  The VarPtr function can be used to
  741. get a pointer to a variable.  If you want to create a pointer
  742. to an address for which you know the segment and offset, you
  743. can use the Ints2Long function to do so, by loading the segment
  744. into the high word and offset into the low word.
  745.  
  746.    PokeB Ptr&, Nr%
  747.  
  748. Ptr&        far pointer
  749. Nr%         byte to place in memory at the pointer location
  750. -------
  751.  
  752. Name  : PokeI                (Poke Integer)
  753.  
  754. This routine pokes an integer into a specified memory location.
  755. The memory location is specified as a pointer, which is a
  756. combined segment and offset value.  The VarPtr function can be
  757. used to get a pointer to a variable.  If you want to create a
  758. pointer to an address for which you know the segment and
  759. offset, you can use the Ints2Long function to do so, by loading
  760. the segment into the high word and offset into the low word.
  761.  
  762.    PokeI Ptr&, Nr%
  763.  
  764. Ptr&        far pointer
  765. Nr%         integer to place in memory at the pointer location
  766. -------
  767.  
  768. Name  : PokeL                (Poke Long)
  769.  
  770. This routine pokes a long integer into a specified memory
  771. location. The memory location is specified as a pointer, which
  772. is a combined segment and offset value.  The VarPtr function
  773. can be used to get a pointer to a variable.  If you want to
  774. create a pointer to an address for which you know the segment
  775. and offset, you can use the Ints2Long function to do so, by
  776. loading the segment into the high word and offset into the low
  777. word.
  778.  
  779.    PokeL Ptr&, Nr&
  780.  
  781. Ptr&        far pointer
  782. Nr%         long integer to place in memory at the pointer posn
  783. -------
  784.  
  785. Name  : Power2I              (Power of 2, Integer)
  786.  
  787. This function returns the result of raising 2 (two) to the
  788. specified power.  It's much faster than using the
  789. floating-point raise-to-power operator in BASIC, and is
  790. especially handy for bit twiddling.
  791.  
  792.    Result% = Power2I(Power%)
  793.  
  794. Power%      power to which to raise two
  795. -------
  796. Result%     two to the specified power
  797.  
  798. Name  : Power2L              (Power of 2, Long)
  799.  
  800. This function returns the result of raising 2 (two) to the
  801. specified power.  It's much faster than using the
  802. floating-point raise-to-power operator in BASIC, and is
  803. especially handy for bit twiddling.
  804.  
  805.    Result& = Power2L(Power%)
  806.  
  807. Power%      power to which to raise two
  808. -------
  809. Result&     two to the specified power
  810.  
  811. Name  : PrtPorts             (Printer Ports)
  812.  
  813. This function returns the number of printer (parallel) ports
  814. installed.
  815.  
  816.    Result% = PrtPorts()
  817.  
  818. -------
  819. Result%   printer ports (0-3)
  820.  
  821. Name  : PtrMatD              (Pointer Matrix Double-precision)
  822.  
  823. This routine initializes each element of a double-precision
  824. array to an increasingly large value.  The value starts at a
  825. specified beginning and is incremented by one for each
  826. subsequent element.
  827.  
  828.    PtrMatD VarPtr(Array#(FirstElem)), Elements%, InitValue#
  829.  
  830. Array#(FirstElem)    first element of array to initialize
  831. Elements%            number of elements to initialize
  832. InitValue#           value to which to init first array element
  833. -------
  834. Array#(FirstElem thru FirstElem + Elements% - 1)    initialized
  835.  
  836. Name  : PtrMatI              (Pointer Matrix Integer)
  837.  
  838. This routine initializes each element of an integer array to an
  839. increasingly large value.  The value starts at a specified
  840. beginning and is incremented by one for each subsequent element.
  841.  
  842.    PtrMatI VarPtr(Array%(FirstElem)), Elements%, InitValue%
  843.  
  844. Array%(FirstElem)    first element of array to initialize
  845. Elements%            number of elements to initialize
  846. InitValue%           value to which to init first array element
  847. -------
  848. Array%(FirstElem thru FirstElem + Elements% - 1)    initialized
  849.  
  850. Name  : PtrMatL              (Pointer Matrix Long)
  851.  
  852. This routine initializes each element of a long integer array
  853. to an increasingly large value.  The value starts at a
  854. specified beginning and is incremented by one for each
  855. subsequent element.
  856.  
  857.    PtrMatL VarPtr(Array&(FirstElem)), Elements%, InitValue&
  858.  
  859. Array&(FirstElem)    first element of array to initialize
  860. Elements%            number of elements to initialize
  861. InitValue&           value to which to init first array element
  862. -------
  863. Array&(FirstElem thru FirstElem + Elements% - 1)    initialized
  864.  
  865. Name  : PtrMatS              (Pointer Matrix Single-precision)
  866.  
  867. This routine initializes each element of a single-precision
  868. array to an increasingly large value.  The value starts at a
  869. specified beginning and is incremented by one for each
  870. subsequent element.
  871.  
  872.    PtrMatS VarPtr(Array!(FirstElem)), Elements%, InitValue!
  873.  
  874. Array!(FirstElem)    first element of array to initialize
  875. Elements%            number of elements to initialize
  876. InitValue!           value to which to init first array element
  877. -------
  878. Array!(FirstElem thru FirstElem + Elements% - 1)    initialized
  879.  
  880. Name  : RRotateI             (Right Rotate Integer)
  881.  
  882. This function returns the result of rotating an integer right
  883. by a specified number of bits.
  884.  
  885.    Result% = RRotateI(Number%, Count%)
  886.  
  887. Number%     number to rotate
  888. Count%      number of bits by which to rotate
  889. -------
  890. Result%     rotated number
  891.  
  892. Name  : RRotateL             (Right Rotate Long)
  893.  
  894. This function returns the result of rotating a long integer
  895. right by a specified number of bits.
  896.  
  897.    Result& = RRotateL(Number&, Count%)
  898.  
  899. Number&     number to rotate
  900. Count%      number of bits by which to rotate
  901. -------
  902. Result&     rotated number
  903.  
  904. Name  : RShiftI             (Right Shift Integer)
  905.  
  906. This function returns the result of shifting an integer right
  907. by a specified number of bits.
  908.  
  909.    Result% = RShiftI(Number%, Count%)
  910.  
  911. Number%     number to shift
  912. Count%      number of bits by which to shift
  913. -------
  914. Result%     shifted number
  915.  
  916. Name  : RShiftL             (Right Shift Long)
  917.  
  918. This function returns the result of shifting a long integer
  919. right by a specified number of bits.
  920.  
  921.    Result& = RShiftL(Number&, Count%)
  922.  
  923. Number&     number to shift
  924. Count%      number of bits by which to shift
  925. -------
  926. Result&     shifted number
  927.  
  928. Name  : SecondUnsq           (Second Unsqueeze)
  929.  
  930. This function returns the second from a compressed time.  It
  931. works in conjunction with the TimeSq time compression function.
  932.  
  933. Note that the second value will always be even, due to the
  934. limited amount of information that can be squeezed into an
  935. integer.
  936.  
  937.    SecondNr% = SecondUnsq(Number%)
  938.  
  939. Number%     compressed time
  940. -------
  941. SecondNr%   second number
  942.  
  943. Name  : SetMatC              (Set Matrix Currency)
  944.  
  945. This routine initializes each element of a currency array to a
  946. specified value.
  947.  
  948.    SetMatC VarPtr(Array@(FirstElem)), Elements%, Value@
  949.  
  950. Array@(FirstElem)    first element of array to initialize
  951. Elements%            number of elements to initialize
  952. Value@               value to which to initialize array
  953. -------
  954. Array@(FirstElem thru FirstElem + Elements% - 1)    initialized
  955.  
  956. Name  : SetMatD              (Set Matrix Double-precision)
  957.  
  958. This routine initializes each element of a double-precision
  959. array to a specified value.
  960.  
  961.    SetMatD VarPtr(Array#(FirstElem)), Elements%, Value#
  962.  
  963. Array#(FirstElem)    first element of array to initialize
  964. Elements%            number of elements to initialize
  965. Value#               value to which to initialize array
  966. -------
  967. Array#(FirstElem thru FirstElem + Elements% - 1)    initialized
  968.  
  969. Name  : SetMatI              (Set Matrix Integer)
  970.  
  971. This routine initializes each element of an integer array to a
  972. specified value.
  973.  
  974.    SetMatI VarPtr(Array%(FirstElem)), Elements%, Value%
  975.  
  976. Array%(FirstElem)    first element of array to initialize
  977. Elements%            number of elements to initialize
  978. Value%               value to which to initialize array
  979. -------
  980. Array%(FirstElem thru FirstElem + Elements% - 1)    initialized
  981.  
  982. Name  : SetMatL              (Set Matrix Long)
  983.  
  984. This routine initializes each element of a long integer array
  985. to a specified value.
  986.  
  987.    SetMatL VarPtr(Array&(FirstElem)), Elements%, Value&
  988.  
  989. Array&(FirstElem)    first element of array to initialize
  990. Elements%            number of elements to initialize
  991. Value&               value to which to initialize array
  992. -------
  993. Array&(FirstElem thru FirstElem + Elements% - 1)    initialized
  994.  
  995. Name  : SetMatS              (Set Matrix Single-precision)
  996.  
  997. This routine initializes each element of a single-precision
  998. array to a specified value.
  999.  
  1000.    SetMatS VarPtr(Array!(FirstElem)), Elements%, Value!
  1001.  
  1002. Array!(FirstElem)    first element of array to initialize
  1003. Elements%            number of elements to initialize
  1004. Value!               value to which to initialize array
  1005. -------
  1006. Array!(FirstElem thru FirstElem + Elements% - 1)    initialized
  1007.  
  1008. Name  : SwapC                (Swap Currency)
  1009.  
  1010. This routine swaps two currency values.
  1011.  
  1012.    SwapC Number1@, Number2@
  1013.  
  1014. Number1@   first number
  1015. Number2@   second number
  1016. -------
  1017. Number1@   former second number
  1018. Number2@   former first number
  1019.  
  1020. Name  : SwapD                (Swap Double-precision)
  1021.  
  1022. This routine swaps two double-precision numbers.
  1023.  
  1024.    SwapD Number1#, Number2#
  1025.  
  1026. Number1#   first number
  1027. Number2#   second number
  1028. -------
  1029. Number1#   former second number
  1030. Number2#   former first number
  1031.  
  1032. Name  : SwapI                (Swap Integer)
  1033.  
  1034. This routine swaps two integers.
  1035.  
  1036.    SwapI Number1%, Number2%
  1037.  
  1038. Number1%   first number
  1039. Number2%   second number
  1040. -------
  1041. Number1%   former second number
  1042. Number2%   former first number
  1043.  
  1044. Name  : SwapL                (Swap Long)
  1045.  
  1046. This routine swaps two long integers.
  1047.  
  1048.    SwapL Number1&, Number2&
  1049.  
  1050. Number1&   first number
  1051. Number2&   second number
  1052. -------
  1053. Number1&   former second number
  1054. Number2&   former first number
  1055.  
  1056. Name  : SwapS                (Swap Single-precision)
  1057.  
  1058. This routine swaps two single-precision numbers.
  1059.  
  1060.    SwapS Number1!, Number2!
  1061.  
  1062. Number1!   first number
  1063. Number2!   second number
  1064. -------
  1065. Number1!   former second number
  1066. Number2!   former first number
  1067.  
  1068. Name  : TimeSq               (Time Squeeze)
  1069.  
  1070. This function compresses a time into a single integer.  This
  1071. provides a very efficient storage format.  Note, however, that
  1072. an integer is not quite large enough to store an exact time--
  1073. the seconds value, if odd, will be rounded down to the next
  1074. closest even number.
  1075.  
  1076. Uncompression is done with HourUnsq, MinuteUnsq, and
  1077. SecondUnsq. See also DateSq, which allows you to compress a
  1078. date value similarly.
  1079.  
  1080. Note that compressed times are not in a format that may be
  1081. readily used for comparison or time math purposes.  If you need
  1082. such capabilities, convert the time to a BASIC time/date serial
  1083. number first-- see your BASIC manual for details.
  1084.  
  1085.    Result% = TimeSq(HourNr%, MinuteNr%, SecondNr%)
  1086.  
  1087. HourNr%     hour number (0-23)
  1088. MinuteNr%   minute number (0-59)
  1089. SecondNr%   second number (0-59; see note on truncation)
  1090. -------
  1091. Result%     compressed time
  1092.  
  1093. Name  : VarPtr               (Variable Pointer)
  1094.  
  1095. This function returns a far pointer to a variable.  It works
  1096. with any variable type except BASIC strings, which are stored
  1097. in an unusual format.  This function is required for passing
  1098. arrays to the PBCwin routines which take arrays as parameters.
  1099. It has not been tested with VB/Win 2.0 arrays, and is likely
  1100. not to work with such arrays if they're over 64k bytes.  Since
  1101. BASIC arrays may move in memory, it is advised that you get the
  1102. pointer to an array just before using it, to minimize the risk
  1103. of accessing the wrong area of memory.
  1104.  
  1105. This function can also be used to provide a pointer for use
  1106. with the various Peek_ and Poke_ routines in PBCwin.
  1107.  
  1108. Note that the PBCwin function, VarPtr, is not identical to the
  1109. DOS BASIC function, VARPTR.  It returns an absolute address
  1110. consisting of both segment and offset, rather than merely an
  1111. offset value.
  1112.  
  1113.    Ptr& = VarPtr(Vbl)
  1114.  
  1115. Vbl        variable for which to get a pointer
  1116. -------
  1117. Ptr&       far pointer to variable
  1118.  
  1119. Name  : YearUnsq             (Year Unsqueeze)
  1120.  
  1121. This function returns the year from a compressed date.  It
  1122. works in conjunction with the DateSq date compression function.
  1123.  
  1124.    YearNr% = YearUnsq(Number%)
  1125.  
  1126. Number%     compressed date
  1127. -------
  1128. YearNr%     year number
  1129.  
  1130.